Update `Tooltip` visual design in interface guidelines + accessibility guidelines #565

langermank · 2023-08-24T00:54:31Z

Goals

Update the visual design of the Tooltip component (remove caret)
Surface the tooltip alternatives into the main interface guidelines to improve discoverability
Add a few more usage guidelines and explain label vs. description

Accessibility page → https://primer-14e523666e-26441320.drafts.github.io/guides/accessibility/tooltip-alternatives
Interface guidelines → https://primer-14e523666e-26441320.drafts.github.io/components/tooltip

TODO

After merging, followup and update these links: https://github.com/primer/design/pull/565/files#r1305710242

content/components/tooltip.mdx

mperrotti · 2023-08-24T22:13:08Z

content/components/tooltip.mdx

+  alt="tooltips rendered in all possible positions surrounding a control"
+/>
+
+## Alternatives to tooltips


Love this section so much

content/components/tooltip.mdx

khiga8

First pass! Thank you for working on this :)
I hope to take a closer look tomorrow!

khiga8 · 2023-08-24T22:23:26Z

content/components/tooltip.mdx

+  alt="tooltips rendered in all possible positions surrounding a control"
+/>
+
+## Alternatives to tooltips


We have a couple of lint rules and doc pages where we cross-reference the existing Tooltip alternatives docs. Let's make sure to update those to avoid a dead link! (I can verify tomorrow which ones those are).

Or could it be sufficient to just cross-reference that page from this section rather than moving it entirely?

Primer CSS Tooltipped

a11y-role-supports-aria-props

NoAriaLabelMisuse

a11y-no-title-attribute

a11y_no_rogue_role_equals_tooltip

PVC Tooltip

I'll follow up with the links outside this repo once this PR merges! ❤️ thank you

khiga8 · 2023-08-24T22:29:17Z

content/components/tooltip.mdx

+If you are unsure which alternative is more suited to your scenario and need help, consult a designer or the GitHub Accessibility team (if you are GitHub staff) for advice.

-Most UI cases don't call for tooltips. Learn some [alternative methods to use in place of tooltips](/../guides/accessibility/tooltip-alternatives).
+## Additional resources


We introduced a new PVC lint rule recently the deprecated Primer CSS tooltipped which we have a ton of debt around that we want to tackle. It looks like the lint rule doc is now on Primer CSS Tooltipped.
Could it make sense to link to it here? :)

khiga8 · 2023-08-24T22:36:20Z

content/components/tooltip.mdx

+
+## Options
+
+### Label


Could it be useful to talk about the underlying markup of the differences between a label and description (e.g. aria-labelledby vs aria-describedby)? One will serve as the accessible name of a control, while the other will supplement it.

We have some more documentation in Primer Rails tooltip (This was originally under an accessibility section in Primer Rails but I think it changed with the recent docs site update!)

Yes, thank you! I had a hard time trying to explain this one so let me see if I can rework it a bit.

I don't think this is shipped in React. Would we want to hold off on this section to avoid confusing people 🤔

(cc: @broccolinisoup who worked on React tooltip :) )

Yes, thank you! I had a hard time trying to explain this one so let me see if I can rework it a bit.

Katie let me know if you want to pair on this or any help with it!

I don't think this is shipped in React. Would we want to hold off on this section to avoid confusing people

Yes! We are going to ship the draft version soon hopefully 🙏🏻 and also the visual changes (i.e. removing the caret) also will be shipped with the draft version so holding off merging this PR until the draft is out would be wise.

lukasoppermann

😍

lukasoppermann · 2023-08-25T06:44:04Z

Hey @langermank could you add a Figma section as well?

content/components/tooltip.mdx

khiga8 · 2023-08-25T14:08:40Z

content/components/tooltip.mdx

+  alt="tooltips rendered in all possible positions surrounding a control"
+/>
+
+## Alternatives to tooltips


Primer CSS Tooltipped

a11y-role-supports-aria-props

NoAriaLabelMisuse

a11y-no-title-attribute

a11y_no_rogue_role_equals_tooltip

PVC Tooltip

khiga8 · 2023-08-25T14:10:29Z

content/components/tooltip.mdx

+
+## Options
+
+### Label


I don't think this is shipped in React. Would we want to hold off on this section to avoid confusing people 🤔

(cc: @broccolinisoup who worked on React tooltip :) )

content/components/tooltip.mdx

khiga8 · 2023-08-25T14:16:28Z

content/components/tooltip.mdx

+    For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also
+    required, and the description will be announced to a screen reader in addition to the label. Keep the description


I think we will want to reword this a bit since this seems to suggest one should set both the label and description prop of the tooltip API which I don't think is the case. Maybe we want to say that when a tooltip supplements a control as a description, we should make sure the control has an accessible name?

<button aria-describedby="tooltip-1">Name of button</button> <tooltip id="tooltip-1">Some supplementary description</tooltip>

we should make sure the control has an accessible name?

I agree with this. Since accessible name could be a visible button text or an aria-label, we can maybe divide the "Description" section into two subsections?

Description for buttons that has a visible name

<button aria-describedby="tooltip-1">Name of button</button> <tooltip id="tooltip-1">Some supplementary description</tooltip>

Description for buttons that doesn't have a visible name

<iconbutton aria-label="icon-button-label" /> <tooltip id="tooltip-1">Some supplementary description</tooltip>

khiga8 · 2023-08-25T14:19:13Z

content/components/tooltip.mdx

+
+## Options
+
+### Label


Could we mention how a label type tooltip should be reserved for icon buttons? The underlying semantic of a label tooltip is aria-labelledby would override any label the button already has.

I feel like this is clear already by saying "For interactive controls with no visible text label" but I will add "such as icon buttons" 😄

broccolinisoup

So cool 🔥 Left some comments, let me know what you think 🙌🏻

content/components/tooltip.mdx

broccolinisoup · 2023-09-13T00:14:43Z

content/components/tooltip.mdx

+
+## Options
+
+### Label


Yes, thank you! I had a hard time trying to explain this one so let me see if I can rework it a bit.

Katie let me know if you want to pair on this or any help with it!

I don't think this is shipped in React. Would we want to hold off on this section to avoid confusing people

Yes! We are going to ship the draft version soon hopefully 🙏🏻 and also the visual changes (i.e. removing the caret) also will be shipped with the draft version so holding off merging this PR until the draft is out would be wise.

broccolinisoup · 2023-09-13T00:29:02Z

content/components/tooltip.mdx

+    For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also
+    required, and the description will be announced to a screen reader in addition to the label. Keep the description


we should make sure the control has an accessible name?

I agree with this. Since accessible name could be a visible button text or an aria-label, we can maybe divide the "Description" section into two subsections?

Description for buttons that has a visible name

<button aria-describedby="tooltip-1">Name of button</button> <tooltip id="tooltip-1">Some supplementary description</tooltip>

Description for buttons that doesn't have a visible name

<iconbutton aria-label="icon-button-label" /> <tooltip id="tooltip-1">Some supplementary description</tooltip>

Co-authored-by: Kate Higa <[email protected]>

…into update-tooltip-docs

Co-authored-by: Kate Higa <[email protected]>

…into update-tooltip-docs

update images

afe6b70

langermank temporarily deployed to github-pages August 24, 2023 01:01 — with GitHub Actions Inactive

cleanup

3c42180

langermank marked this pull request as ready for review August 24, 2023 01:13

langermank requested a review from a team as a code owner August 24, 2023 01:13

langermank marked this pull request as draft August 24, 2023 01:14

langermank temporarily deployed to github-pages August 24, 2023 01:20 — with GitHub Actions Inactive

attempt to consolidate

bcc57d4

langermank temporarily deployed to github-pages August 24, 2023 21:39 — with GitHub Actions Inactive

cleanup

b987451

langermank temporarily deployed to github-pages August 24, 2023 21:55 — with GitHub Actions Inactive

fix box hopefully

bc3a41d

langermank temporarily deployed to github-pages August 24, 2023 22:04 — with GitHub Actions Inactive

langermank marked this pull request as ready for review August 24, 2023 22:07

langermank requested a review from khiga8 August 24, 2023 22:07

langermank commented Aug 24, 2023

View reviewed changes

content/components/tooltip.mdx Outdated Show resolved Hide resolved

mperrotti approved these changes Aug 24, 2023

View reviewed changes

khiga8 reviewed Aug 24, 2023

View reviewed changes

lukasoppermann approved these changes Aug 25, 2023

View reviewed changes

khiga8 reviewed Aug 25, 2023

View reviewed changes

broccolinisoup self-requested a review August 28, 2023 01:17

broccolinisoup reviewed Sep 13, 2023

View reviewed changes

broccolinisoup mentioned this pull request Sep 14, 2023

Tooltip: Tooltip V2 as an experimental/draft with the new popover API primer/react#3394

Merged

11 tasks

langermank and others added 6 commits September 15, 2023 11:29

Update content/components/tooltip.mdx

f8b8de1

Update content/components/tooltip.mdx

008c153

Co-authored-by: Kate Higa <[email protected]>

Update content/components/tooltip.mdx

eb40703

Co-authored-by: Kate Higa <[email protected]>

Update content/components/tooltip.mdx

dc48f22

Co-authored-by: Kate Higa <[email protected]>

Update content/components/tooltip.mdx

1ca5164

Co-authored-by: Kate Higa <[email protected]>

feedback

b1d2590

langermank and others added 7 commits October 6, 2023 11:18

Merge branch 'update-tooltip-docs' of https://github.com/primer/design …

71a7004

…into update-tooltip-docs

Update content/components/tooltip.mdx

7f69b4a

Co-authored-by: Kate Higa <[email protected]>

Merge branch 'update-tooltip-docs' of https://github.com/primer/design …

3091571

…into update-tooltip-docs

more feedback

fb208e7

cleanup

6502600

Merge branch 'main' into update-tooltip-docs

869046e

add figma

2ea653e

langermank temporarily deployed to github-pages October 6, 2023 18:56 — with GitHub Actions Inactive

cleanup

27254c0

langermank temporarily deployed to github-pages October 6, 2023 19:28 — with GitHub Actions Inactive

langermank merged commit b9ad2cf into main Oct 9, 2023

langermank deleted the update-tooltip-docs branch October 9, 2023 15:29

		For interactive controls that require additional context, a tooltip can be used to provide it. The `label` is also
		required, and the description will be announced to a screen reader in addition to the label. Keep the description

Update Tooltip visual design in interface guidelines + accessibility guidelines #565

Update Tooltip visual design in interface guidelines + accessibility guidelines #565

Uh oh!

Conversation

langermank commented Aug 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goals

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

khiga8 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukasoppermann left a comment

Choose a reason for hiding this comment

Uh oh!

lukasoppermann commented Aug 25, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

broccolinisoup left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Update `Tooltip` visual design in interface guidelines + accessibility guidelines #565

Update `Tooltip` visual design in interface guidelines + accessibility guidelines #565

langermank commented Aug 24, 2023 •

edited

Loading